Anonymous Git Node
Mirrored from https://github.com/gmlewis/asic-reticulum synced 2m ago
ASIC-based Reticulum hardware project — the reference island devices
>asic-reticulum
Hardware accelerator ASIC for the Reticulum Network Stack authored in SpinalHDL (Scala DSL).
This project implements the silicon offload targets specified in ASIC-Plans.md,
targeting open-source silicon flows (Tiny Tapeout, OpenLane, SkyWater sky130, and IHP SG13G2).
For an exhaustive technical deep-dive into all design decisions, mathematical formulations, hardware pipelines, and verification results from Milestones 0 through 9, see Design-Walkthrough.md.
│ [!WARNING] ### ⚠️ Emergency, Hardware, and Safety Disclaimer NOT A CERTIFIED LIFE-SAFETY DEVICE ·
│ DIY HARDWARE & BATTERY HAZARDS. Hardware platforms and firmware described in this repository
│ operate over unlicensed, best-effort radio frequencies and are NOT connected to official 911/112
│ emergency services, government rescue agencies, or COSPAS-SARSAT search-and-rescue satellites.
│ DIY electronics assembly involving lithium-ion batteries carries inherent risks of thermal
│ runaway, fire, and explosion. Operators are solely responsible for telecommunications regulatory
│ compliance (FCC/ETSI). Users assume all risks of fabrication, testing, and deployment. Read
│ **DISCLAIMER.md** for
│ the full legal terms and release of liability.
│ [!TIP] ### Looking to build or flash the hardware devices? Jump straight to the **Reticulum
│ Hardware Projects
│ Guide** for
│ complete purchasing BOMs, step-by-step assembly, pre-built binary downloads, and zero-install
│ in-browser web flashing for all three standalone off-grid hardware projects: - Project 1: Pocket
│ Linux Terminal (Raspberry Pi Zero 2W + SPI LCD + CardKB + LoRa + full TUI) - Project 2:
│ Standalone Pocket Communicator (ESP32-C5 RISC-V SoC + LCD + CardKB + LoRa) - Project 3:
│ Autonomous Pocket Hub & Repeater (ESP32-C5 + LoRa + Wi-Fi 6 SoftAP)
1. Architectural Overview
T383838asic-reticulum offloads the computationally intensive, fixed-function cryptographic bottlenecks of Reticulum:
1. LXMF Stamp Grinding (SHA-256 Hashcash):
• Deeply pipelined SHA-256 compression engine with midstate restore.
• Autonomous nonce increment and single-cycle Leading Zero Counter (LZC).
• Accelerates proof-of-work generation by orders of magnitude while preserving battery life on embedded nodes.
2. X25519 ECDH & Ed25519 Sign/Verify:
• Shared Montgomery ladder field arithmetic unit (~20–40k gates).
• Offloads link establishment handshakes and announce signature verifications.
3. AES-128-CBC + HMAC-SHA256 (Fernet Token Engine):
• Streaming packet encryption/decryption pipeline.
• Accelerates T383838gorrcd chat room broadcast fanouts (burst per-member link encryption).
4. Host Interconnect: 4-bit Quad-SPI (QSPI @ 40–80 MHz) + Hardware IRQ:
• 7-pin interface (T383838CLK, T383838CS, T383838IO0..IO3, T383838IRQ).
• Streams 20–40 MB/s directly via the host MCU's General DMA (GDMA) engine (e.g. ESP32-C5) with zero CPU polling and zero memory copies.
2. Why SpinalHDL?
• 100% Free & Open-Source (LGPL): Runs completely locally with standard T383838sbt and JVM; zero proprietary licenses or cloud preprocessors.
• First-Class Streams & Bus Protocols (T383838spinal.lib): Native T383838Stream (T383838valid/T383838ready handshakes) with automatic backpressure, skid buffers, and FIFOs. Generates APB3 and AXI4-Lite register maps in single lines.
• Pipelining Without the Pain (T383838spinal.lib.pipeline): Expressive stage retiming and hazard detection without manual register plumbing.
• Native Symbiosis with RISC-V: Open-source softcores VexRiscv (RV32) and NaxRiscv (RV64) are written in SpinalHDL, allowing custom instruction co-processor extensions (T383838Plugin[VexRiscv]).
• Clean Verilog Output: Compiles into standard, human-readable Verilog-2001 or SystemVerilog consumed natively by OpenLane, Yosys, and Tiny Tapeout.
3. Project Structure
T282828
asic-reticulum/
├── LICENSE
├── README.md
├── build.sbt # Scala & SpinalHDL dependency configuration
├── project/
│ └── build.properties # sbt runner version (1.10.7)
├── hw/
│ ├── spinal/
│ │ └── reticulum/
│ │ ├── crypto/
│ │ │ ├── LeadZeroCounter.scala # Difficulty comparator for IFAC stamps
│ │ │ ├── Sha256Constants.scala # FIPS 180-4 H0 vector and K0..K63 constants
│ │ │ ├── Sha256Round.scala # Single-cycle SHA-256 compression step
│ │ │ ├── Sha256Pipe.scala # Pipelined SHA-256 engine with midstate restore
│ │ │ ├── Stamper.scala # Autonomous IFAC Hashcash stamp grinder
│ │ │ ├── Field25519.scala # GF(2^255-19) modular arithmetic primitives
│ │ │ ├── X25519Ladder.scala # Constant-time Montgomery ladder X25519 engine
│ │ │ ├── AesConstants.scala # AES S-Box, InvS-Box, and Rcon constants
│ │ │ ├── AesCore.scala # 10-cycle iterative AES-128 encrypt/decrypt core
│ │ │ ├── HmacSha256.scala # RFC 2104 / FIPS 198-1 HMAC-SHA256 streaming core
│ │ │ └── TokenEngine.scala # Fernet-style AES-128-CBC + HMAC-SHA256 packet engine
│ │ ├── bus/
│ │ │ ├── QspiSlave.scala # 4-bit QSPI slave transceiver with Stream RX/TX
│ │ │ ├── QspiCommandDecoder.scala # Command decoder FSM & accelerator control lines
│ │ │ └── QspiTop.scala # Top-level 7-pin physical interface & interconnect
│ │ ├── fpga/
│ │ │ └── FpgaTop.scala # Multi-engine FPGA top-level wrapper
│ │ └── tt/
│ │ └── TinyTapeoutTop.scala # Tiny Tapeout top module (tt_um_gmlewis_reticulum)
├── openlane/ # OpenLane physical design & synthesis configs
│ ├── config.json # OpenLane 2 configuration (Sky130 50 MHz)
│ ├── config.tcl # OpenLane 1 configuration
│ └── pin_order.cfg # Macro perimeter pin placement
├── test/ # Cocotb verification testbench for Tiny Tapeout CI
│ ├── tb.v # Verilog simulation top wrapper
│ ├── test.py # Cocotb test cases (Status, X25519, Token Seal/Open)
│ └── Makefile # Icarus Verilog + Cocotb makefile
├── src/ # Standalone synthesis Verilog for Tiny Tapeout submission
│ └── tt_um_gmlewis_reticulum.v
├── info.yaml # Tiny Tapeout project manifest & pinout specification
├── sim/ # Table-driven simulation test suites (ScalaTest + SpinalSim)
│ └── reticulum/
│ ├── crypto/
│ │ ├── LeadZeroCounterTest.scala # 32-bit & 256-bit priority sweeps
│ │ ├── Sha256RoundTest.scala # FIPS vectors & randomized stress tests
│ │ ├── Sha256PipeTest.scala # Pipelining, midstate restore & backpressure tests
│ │ ├── StamperTest.scala # Autonomous candidate search & IRQ verification
│ │ ├── Field25519Test.scala # GF(2^255-19) add/sub/mul/sqr/reduction tests
│ │ ├── X25519LadderTest.scala # RFC 7748 Vectors 1 & 2 + abort verification
│ │ ├── AesCoreTest.scala # FIPS 197 AES-128 encrypt & decrypt verification
│ │ ├── HmacSha256Test.scala # RFC 4231 HMAC test cases & multi-block verification
│ │ └── TokenEngineTest.scala # In-place Seal, Open, and PKCS#7 padding validation
│ ├── bus/
│ │ ├── QspiSlaveTest.scala # Multi-byte RX/TX & CS frame reset tests
│ │ ├── QspiCommandDecoderTest.scala # Opcode decoding, payload streaming & IRQ pulses
│ │ └── QspiTopTest.scala # End-to-end QSPI grinding, IRQ & readout verification
│ ├── tt/
│ │ └── TinyTapeoutTopTest.scala # TT pin mapping, bus turnaround & crypto tests
│ └── parity/
│ ├── GoldenVectors.scala # Precomputed golden vectors generated from go-reticulum
│ └── GoReticulumParityTest.scala # Cross-repo verification harness (Stamper, QspiTop, Sha256Pipe, X25519, Token)
└── gen/ # Synthesis-ready generated Verilog output
4. Quick Start
Prerequisites
• Java 17 (LTS)
• sbt (Scala Build Tool)
• Verilator 5 (for cycle-accurate SpinalSim testbenches)
On macOS:
T282828
T8b949e# scala for SpinalHDL (in ~/.bashrc):
Te6edf3startscalaTb4b4b4(Tb4b4b4) Tb4b4b4{
Tffa657export Te6edf3PATHTff7b72=Ta5d6ff"$HOME/.jenv/bin:/opt/homebrew/opt/openjdk@17/bin:$PATH"
Tffa657eval Ta5d6ff"$(jenv init -)"
Tb4b4b4}
T8b949e# Initialize Java 17 and sbt environment from command-line:
Te6edf3startscala
Compiling the Hardware Descriptions
T282828
Te6edf3sbt Te6edf3compile
Running the Unit Test Suites
T282828
Te6edf3sbt Tffa657test
Generating Verilog
To generate standard, synthesis-ready Verilog into T383838hw/gen/:
• Generate Leading Zero Counter (T383838LeadZeroCounter.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.crypto.LeadZeroCounterVerilog"
• Generate SHA-256 Round Function (T383838Sha256Round.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.crypto.Sha256RoundVerilog"
• Generate SHA-256 Pipelined Engine (T383838Sha256Pipe.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.crypto.Sha256PipeVerilog"
• Generate Autonomous Stamp Grinder (T383838Stamper.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.crypto.StamperVerilog"
• Generate 4-bit QSPI Slave Transceiver (T383838QspiSlave.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.bus.QspiSlaveVerilog"
• Generate Field Multiplier (T383838FieldMultiplier.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.crypto.FieldMultiplierVerilog"
• Generate X25519 Montgomery Ladder (T383838X25519Ladder.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.crypto.X25519LadderVerilog"
• Generate AES-128 Iterative Core (T383838AesCore.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.crypto.AesCoreVerilog"
• Generate Streaming HMAC-SHA256 Engine (T383838HmacSha256.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.crypto.HmacSha256Verilog"
• Generate Token Seal/Open Engine (T383838TokenEngine.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.crypto.TokenEngineVerilog"
• Generate Top-Level QSPI Crypto Engine (T383838QspiTop.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.bus.QspiTopVerilog"
• Generate FPGA Accelerator Top-Level (T383838FpgaTop.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.fpga.FpgaTopVerilog"
• Generate Tiny Tapeout Top-Level (T383838tt_um_gmlewis_reticulum.v):
T282828
Te6edf3sbt Ta5d6ff"runMain reticulum.tt.TinyTapeoutVerilog"
Inspect the generated outputs:
T282828
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3LeadZeroCounterTff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3Sha256RoundTff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3Sha256PipeTff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3StamperTff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3FieldMultiplierTff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3X25519LadderTff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3AesCoreTff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3HmacSha256Tff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3TokenEngineTff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3QspiSlaveTff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3QspiTopTff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3FpgaTopTff7b72.Td2a8ffv
Te6edf3cat Te6edf3hwTff7b72/Te6edf3genTff7b72/Te6edf3tt_um_gmlewis_reticulumTff7b72.Td2a8ffv
Te6edf3cat Te6edf3srcTff7b72/Te6edf3tt_um_gmlewis_reticulumTff7b72.Td2a8ffv
5. FPGA & ESP32-C5 Hardware-In-The-Loop (HIL) Testbed
Milestone 8 provides complete synthesis wrappers, physical pin constraints, and host firmware drivers for real-world hardware validation:
• Target FPGA Platforms:
• Sipeed Tang Primer 25K (Gowin GW5A-25, 23k LUTs, 4x TokenEngines) — constraints in hw/fpga/tang_primer_25k.cst.
• QMTECH AMD Artix-7 (XC7A35T / XC7A100T) — constraints in hw/fpga/qmtech_artix7.xdc.
• Clock & timing false paths defined in hw/fpga/timing.sdc.
• ESP32-C5 Host Driver (fw/esp32c5/):
• ESP-IDF C driver using hardware GP-SPI master (T383838SPI2_HOST) with GDMA channel up to 40-80 MHz.
• Edge-triggered interrupt handling on T383838IRQ_N with zero host CPU polling.
• Complete self-test suite exercising X25519, 4-way Token pool, and IFAC Hashcash grinding.
• Automated HIL Test Runner (tools/hil/hil_test_runner.py):
T282828
T8b949e# Hardware test over USB-UART:
Te6edf3python3 Te6edf3toolsTff7b72/Te6edf3hilTff7b72/Te6edf3hil_test_runnerTff7b72.Td2a8ffpy Tff7b72--Te6edf3port Tff7b72/Te6edf3devTff7b72/Te6edf3ttyUSB0 Tff7b72--Te6edf3baud T79c0ff115200
T8b949e# Simulation mock test:
Te6edf3python3 Te6edf3toolsTff7b72/Te6edf3hilTff7b72/Te6edf3hil_test_runnerTff7b72.Td2a8ffpy Tff7b72--Te6edf3sim
6. Tiny Tapeout & OpenLane ASIC Synthesis Flow
Milestone 9 packages the complete cryptographic accelerator for tapeout on SkyWater 130nm (T383838sky130_fd_sc_hd) through Tiny Tapeout.
Tiny Tapeout Pinout Mapping
┌─────────────┬───────────────┬────────────┬───────────────────────────────────────────────────┐
│ Pin Name │ Type │ Signal │ Function Description │
├─────────────┼───────────────┼────────────┼───────────────────────────────────────────────────┤
│ T383838clk │ Input │ T383838clk │ System clock (typically 20–50 MHz) │
│ T383838rst_n │ Input │ T383838rst_n │ Active-low asynchronous reset │
│ T383838ena │ Input │ T383838ena │ Tile enable from Tiny Tapeout multiplexer │
│ T383838ui_in[0] │ Input │ T383838qspi_sclk │ Quad-SPI bus clock (Mode 0) │
│ T383838ui_in[1] │ Input │ T383838qspi_cs_n │ Quad-SPI active-low chip select │
│ T383838ui_in[7:2] │ Input │ — │ Reserved inputs (tied low internally) │
│ T383838uio[0] │ Bidirectional │ T383838qspi_io0 │ 4-bit Quad-SPI Data Bit 0 (MOSI in 1-bit mode) │
│ T383838uio[1] │ Bidirectional │ T383838qspi_io1 │ 4-bit Quad-SPI Data Bit 1 (MISO in 1-bit mode) │
│ T383838uio[2] │ Bidirectional │ T383838qspi_io2 │ 4-bit Quad-SPI Data Bit 2 (WP# in standard SPI) │
│ T383838uio[3] │ Bidirectional │ T383838qspi_io3 │ 4-bit Quad-SPI Data Bit 3 (HOLD# in standard SPI) │
│ T383838uio[7:4] │ Bidirectional │ — │ Reserved bidirectional lines (high-Z) │
│ T383838uo_out[0] │ Output │ T383838qspi_irq_n │ Active-low completion interrupt to host MCU │
│ T383838uo_out[1] │ Output │ T383838busy │ Active-high status (engine actively computing) │
│ T383838uo_out[2] │ Output │ T383838heartbeat │ ~1.5 Hz diagnostic blinker (50 MHz / 2^25) │
│ T383838uo_out[7:3] │ Output │ — │ Reserved status outputs (driven low) │
└─────────────┴───────────────┴────────────┴───────────────────────────────────────────────────┘
Automated OpenLane Synthesis
Physical layout and GDS generation targeting T383838sky130A standard cells:
T282828
T8b949e# Automated local OpenLane run (via Docker):
Tff7b72.Tff7b72/Te6edf3scriptsTff7b72/Te6edf3runTff7b72-Te6edf3openlaneTff7b72.Td2a8ffsh
Configuration files:
• openlane/config.json: OpenLane 2 configuration with 50 MHz clock constraint (T383838CLOCK_PERIOD = 20.0 ns).
• openlane/config.tcl: Backward-compatible OpenLane 1 configuration.
• openlane/pin_order.cfg: Standard perimeter pin placements conforming to Tiny Tapeout macro slots.
• info.yaml: Tiny Tapeout metadata manifest (tile allocation: T3838384x2, 50 MHz clock).
Cocotb Hardware Verification
Tiny Tapeout automated CI verifies the top-level netlist using Cocotb and Icarus Verilog:
T282828
T8b949e# Run cocotb testbench:
Te6edf3make Tff7b72-Te6edf3C Tffa657test
Tests validate status register readout, 256-bit X25519 point multiplication, and Token seal/open authenticated encryption roundtrips through the top-level pins.
7. Implementation Roadmap
• [x] Milestone 0: Repository setup, build system (T383838build.sbt), and SpinalHDL toolchain validation.
• [x] Milestone 1: Core primitives — T383838LeadZeroCounter and T383838Sha256Round.
• [x] Milestone 2: Multi-stage pipelined SHA-256 engine with midstate restore register.
• [x] Milestone 3: Autonomous IFAC Hashcash Stamp Grinder with nonce streaming and T383838meetsTarget interrupt assertion.
• [x] Milestone 4: 4-bit QSPI slave interface (T383838Stream handshake + command decoder FSM + 7-pin T383838QspiTop integration).
• [x] Milestone 5: Verification harness comparing SpinalSim / Verilator against T383838go-reticulum golden test vectors.
• [x] Milestone 6: Montgomery ladder (X25519 / Ed25519) field arithmetic core.
• [x] Milestone 7: AES-128-CBC + HMAC-SHA256 Token engine (with parameterized multi-engine pool support).
• [x] Milestone 8: FPGA emulation, synthesis, and hardware-in-the-loop (HIL) testbed with ESP32-C5.
• [x] Milestone 9: Top-level chip integration, OpenLane synthesis, and Tiny Tapeout GDS submission.
Served by rngit 0.133.0 - Generated in 0s